home *** CD-ROM | disk | FTP | other *** search
/ Mac Power 1997 December / MACPOWER-1997-12.ISO.7z / MACPOWER-1997-12.ISO / AMUG / PROGRAMMING / Raven 1.2.sit / Raven 1.2 / Source / Foundation / OS / ZHandle.h < prev    next >
Text File  |  1997-06-20  |  5KB  |  154 lines
  1. /*
  2.  *  File:        ZHandle.h
  3.  *  Summary:    A class to encapsulate relocatable memory.
  4.  *  Written by:    Jesse Jones
  5.  *
  6.  *    Abstract:    THandle uses reference counting so that when an 
  7.  *                THandle is copied the old and new objects point to 
  8.  *                the same block of memory. This means that THandle 
  9.  *                objects can be treated just like regular OSMemHandle's. 
  10.  *                In particular, they can be passed by value without 
  11.  *                allocating a new chunk of memory.
  12.  *
  13.  *    Usage:        There are three ways to allocate memory in Raven: operator new, 
  14.  *                THandle, and TPointer. The new operator should be used to 
  15.  *                allocate small amounts of memory that won't change size. 
  16.  *                THandle should be used for large chunks of memory. TPointer 
  17.  *                should be used for large chunks of memory that cannot move.
  18.  *
  19.  *                When using THandle try to minimize the amount of 
  20.  *                time the handle is locked down: while it's locked the 
  21.  *                heap may be fragmented. If a memory allocation happens 
  22.  *                when the heap is fragmented it may fail.
  23.  *
  24.  *  Copyright ｩ 1996 Jesse Jones. 
  25.  *    For conditions of distribution and use, see copyright notice in ZTypes.h  
  26.  *
  27.  *  Change History (most recent first):
  28.  *
  29.  *         <2>     6/20/97    JDJ        Ctors use new SHandleOptions to work around ambiguity problems.
  30.  *         <1>     1/14/96    JDJ        Created
  31.  */
  32.  
  33. #pragma once
  34.  
  35. #include <ZConstants.h>
  36. #include <ZLockable.h>
  37. #include <ZTypes.h>
  38.  
  39.  
  40. //-----------------------------------
  41. //    Forward References
  42. //
  43. class ZHandleRef;
  44.  
  45.  
  46. // ===================================================================================
  47. //    struct SHandleOptions
  48. //        Used to work around ambiguities in the ctors.
  49. // ===================================================================================
  50. struct SHandleOptions {
  51.     int options;
  52.     
  53.                 SHandleOptions()            {options = kDontZeroBytes + kUseAppHeap;}
  54.  
  55.     explicit    SHandleOptions(int opt)        {options = opt;}
  56. };
  57.  
  58.  
  59. // ===================================================================================
  60. //    class THandle
  61. // ===================================================================================
  62. class THandle : public MBaseLockable {
  63.  
  64. //-----------------------------------
  65. //    Initialization/Destruction
  66. //
  67. public:
  68.     virtual             ~THandle();
  69.  
  70.     explicit             THandle(ulong bytes = 0, const SHandleOptions& options = SHandleOptions());
  71.                         // The compiler will complain if you write code that looks like
  72.                         // THandle(0, kUseTempHeap). 
  73.  
  74.                         THandle(Handle takeHandle);
  75.                         // Accepts responsibility for the Handle provided in takeHandle. 
  76.                         // If the handle is a Mac resource it is loaded (if neccesary) 
  77.                         // and then detached.
  78.                             
  79.                         THandle(ResType type, ResID id, const SHandleOptions& options = SHandleOptions(), short fileRef = kNoFileRefNum);
  80.                         // Uses ReadPartialResource to read the resource into the handle.
  81.  
  82.                         THandle(ResType type, const string& name, const SHandleOptions& options = SHandleOptions(), short fileRef = kNoFileRefNum);
  83.  
  84.                         THandle(const THandle& rhs);
  85.  
  86.             THandle&     operator=(const THandle& rhs);
  87.     
  88. //-----------------------------------
  89. //    API
  90. //
  91. public:
  92.     // ----- Conversion operators -----
  93.                         operator Handle() const;
  94.  
  95.     // ----- Access -----
  96.             const Byte* GetPtr() const;
  97.  
  98.             Byte*         GetPtr();
  99.                 
  100.             const Byte* GetUnsafePtr() const;
  101.                         // The handle may not be locked so be careful!
  102.  
  103.             Byte*         GetUnsafePtr();
  104.         
  105.     // ----- Sizing -----
  106.             ulong         GetSize() const;
  107.                         // Ignores the tail if present.
  108.             
  109.             void         SetSize(ulong bytes, bool zeroBytes = kDontZeroBytes);    
  110.                         // Note that this throws an exception if it fails. Also the
  111.                         // handle should not be locked. If zeroBytes is set new bytes
  112.                         // are zeroed instead of being uninitialized.
  113.  
  114.     // ----- Debugging -----
  115.             void         AddTail();
  116.                         // Adds a 4-byte tail to the end of the handle. This can be used 
  117.                         // to check that you're not writing past the end of the handle.
  118.                 
  119.             void         CheckTail() const;
  120.             
  121.             void         RemoveTail();
  122.         
  123.     // ----- Misc -----
  124.             bool         CanPurge(Handle gzHandle) const;
  125.             
  126.             ulong         PurgeableBytes() const;
  127.  
  128.             void         Detach();
  129.                         // If the letter is being shared this will create a new letter
  130.                         // referenced only by 'this'.
  131.                         
  132.             bool        operator==(const THandle& rhs) const;
  133.  
  134.             bool        operator!=(const THandle& rhs) const        {return !this->operator==(rhs);}
  135.  
  136. //-----------------------------------
  137. //    Inherited API
  138. //
  139. public:
  140.     virtual void         Lock(bool moveHigh = kDontMoveHigh);
  141.  
  142.     virtual void         Unlock();
  143.  
  144.     virtual bool         IsLocked() const;
  145.         
  146. //-----------------------------------
  147. //    Member data
  148. //
  149. protected:
  150.     ZHandleRef*        mHandleRef;
  151. };
  152.  
  153.  
  154.